package edu.wpi.cs509.ui.intfc;

import edu.wpi.cs509.clientlogic.UserSession;
import edu.wpi.cs509.common.exceptions.ServerUnreachable;


/**
 * This interface defines the methods that the Stratego UI will
 * invoke in the Client Logic to initiate requests made by the user.
 * All methods in this interface are ASYNCHRONOUS and non-blocking.
 * The Client Logic will call back to the UI with the results at 
 * some later time, using the methods defined in the ClientLogicNotify
 * interface.
 * 
 * @author afoltan
 *
 */
public interface ClientLogicRequest {
	
	/**
	 * Starts a user session by logging the user into the Stratego server
	 * 
	 * Response:
	 * 		notifyLoginSuccess
	 *      notifyFailure( InvalidCredentials )
	 * 
	 * @param username - log in user name
	 * @param password - user password
	 */
	void login( String username, String password, String host ) throws ServerUnreachable;
	
	/**
	 * Ends a user session by logging the user out of the Stratego server
	 * 
	 * Response:
	 * 		<none>
	 * 
	 * @param session - the client logic context from the call to login()
	 */
	void logout( UserSession session );

	/**
	 * Retrieves the leaderboard information for the top players.
	 * 
	 * Response:
	 * 		notifyLeaderBoard
	 * 
	 * @param rank - the starting rank position to return
	 * @param count - the number of player stats to return following rank (inclusive).
	 */
	void requestLeaderBoard( int rank, int count ) throws ServerUnreachable;
	
	/**
	 * Retrieves the leaderboard information for the named players.
	 * 
	 * Response:
	 * 		notifyLeaderBoard
	 * 
	 * @param username - the name of the player to start from 
	 * @param count - the number of player stats to return following rank (inclusive).
	 */
	void requestLeaderBoard( String username, int count ) throws ServerUnreachable;
	
	/**
	 * Retrieves the stats for the named player.
	 * 
	 * Response:
	 * 		notifyPlayerStats
	 * 
	 * @param username - the name of the player for whom the stats will be retrieved.
	 */
	void requestPersonalStats( String username ) throws ServerUnreachable;
	
	/**
	 * Retrieves a list of all games from the server.
	 * These are both joinable and observable games.
	 * 
	 * Response:
	 * 		notifyGames
	 * 
	 */
	void requestGames() throws ServerUnreachable;
	
	/**
	 * Starts a new game on the server and makes the caller player 1.
	 * 
	 * Response:
	 * 		notifyGameJoined
	 * 		notifyFailure( ServerCapacityReached )
	 * 
	 * @param session - the user session for player 1
 	 * @param events - the interface of methods that the Client Logic
	 *              can use to notify the UI of asynchronous events related 
	 *              to the game
	 */
	void startNewGame( UserSession session, GameEventNotify notify ) throws ServerUnreachable;
	
	/**
	 * The specified user joins a game as player2.
	 * 
	 * Response:
	 * 		notifyGameJoined
	 * 		notifyFailure( GameNotFound )
	 * 		notifyFailure( GameNotJoinable )
	 * 
	 * @param session - the user session
	 * @param gameID - the ID of the game to join
	 * param notify - the handler for events associated with this game
	 */
	void joinGame( UserSession session, long gameID, GameEventNotify notify ) throws ServerUnreachable;

	/**
	 * Adds the specified user as a spectator of this game.
	 * 
	 * Response:
	 * 		notifyGameObserved
	 * 		notifyFailure( GameNotFound )
	 * 
	 * @param session - the user session that wants to spectate
	 * @param gameID - the ID of the game to join
	 * param notify - the handler for events associated with this game
	 */
	void spectateStart( UserSession session, long gameID, GameEventNotify notify ) throws ServerUnreachable;

	/**
	 * Retrieves the Stratego Rules for display
	 * 
	 * Response:
	 * 		notifyRulesPage
	 * 
	 * @return
	 */
	void requestStrategoRules() throws ServerUnreachable;
}
